Creating Icon themes for GNOME 2.1/2.2

Version 0.2 - December 18, 2002


Written by Andrew Johnson(with help, hints, and general criticism from the regular denizens of #gnome-art)

modeled after the "Creating themes for Nautilus" HOW-TO by Christian Fredrik Kalager Schaller

Gnome 2.1/2.2 has great integrated theme capabilities both for the file and device type icons such as are used by nautilus, and application icons such as are used in the GNOME menu and many other GNOME apps as well. This tutorial which try and explain how the new GNOME 2.1/2.2 Icon theming works(as based on the spec from freedesktop.org) and how you can make icon themes for the newest versions of your favorite desktop.


Understanding the GNOME2.1/2.2 Icon theme engine

Clean up this parapraph, its meandering, run-on, and highly confusing.. especially for an introduction.

The first thing you need to know is how the new GNOME theme engine works.  In general GNOME2 stores its icons in /usr/share/icons or /usr/local/share/icons for system wide themes, and ~/.icons for user themes. In these directories you should be able to see sub-directories with the names of the themes that you currently have installed on your system, where each of these themes is composed of an index.theme file describing the theme (theme name etc, icon types, default sizes, and so forth); and multiple icons and .icon files categorized into sub-folders by size and type, such as emblems & filesystems.


Need another paragraph here, or better flow from the first paragraph to this one..

When creating icons for GNOME2 you have a few specific formats to choose from, namely PNG, SVG and XPM. PNG and SVG are the two recommended ones for bitmap icons and vector graphics icons respectively, while the XPM support is in there mainly for legacy support(ex. making a new theme from older GNOME1/Nautilus1 Icons).  It is important to note that there is no need to provide multiple sized versions of icons in the SVG format, as they can be scaled to any size neccesary without reducing their displayed quality. Note that SVG icons are more CPU intensive and will usually require more CPU power for the computer to render, so slow machines might have problems running GNOME2 using such themes. As such it is often times good practice too supply a scaled bitmap (png) version of themes for those with older hardware.


Need another paragraph here, perhaps describing general things to do to prepare to make a new theme..

I suggest starting with another theme when creating a new theme and then replace the icons one by one.  Creating a directory with the same name as your planned theme and creating the index.theme inside it is all that is needed to make the theme available in the Gnome theme manager.


Step 1. Creating an index.theme configuration file


To begin making your theme, create a folder of the same name as you wish to call your theme, or by copying another theme as suggested above, and then you will be ready to start setting up the theme.

The most important aspect of the icon theme is index.theme, an ini style configuration file which describes the theme in various sections. The main and most important section is broken down as follows :


This whole bit needs to be put into a user friendly, easily readble layout... ideas anyone? I accept/prefer actual code as a valid suggestion. [IconTheme]

this section describes the layout of the theme in a very simple farely intuitive way

Name=ThemeName

this field represents the name of the theme as should be displayed in the icons section of the Gnome Theme Manager, it is very important that the themes folder name matches this field

Comment=This is the theme comment

this field represents the comment of the theme as is sometimes displayed in Gnome Theme Manager

Directories=iconsize/iconcategory1,iconsize/iconcategory1,iconsize2/iconcategory1

this field represents the directories which contain the actual icons

Inherits=RootTheme

this field represents the root theme from which this theme inherits. If the theme does not supply a particular icon, GNOME will look in this root theme for icons before falling back on the system defaults.


Each directory as listed in the IconTheme section will also need its own section to describe icon size and type :


[Directory]

this section describes the charecteristics of the icons located in this directory

Size=IconSize

this field represents the size of the icons located in this directory if they are bitmap icons (PNG or XPM), or the default scale if they are scalable icons (aka SVG)

MinSize=IconSize

this field represents the mimimum size that scalable icons (SVG) located in this directory can be scaled too.

MaxSize=IconSize

this field represents the maximum size that scalable icons (SVG) located in this directory can be scaled too.

Threshold=SizeThreshold

this field represents the maximum size threshold that bitmap icons (PNG/XPM) located in this directory be used for if the icon type is Threshold.

Context=IconCategory

this field represents the category or context in which these icons are used. This value can be FileSystems (for Folder or HardDrives), Emblems, Applications, Devices, or MimeTypes

Type=IconType

this field represents the type of icons located in this directory, it can be Scalable for Scalable Icons (SVG), Threshold or Fixed(I have seen Scaled used as well, is this valid?!) for Bitmap Icons(PNG or XPM)


As an example here is a somewhat truncated index.theme as taken from the GNOME2 HighContrast Icon theme, part of the GNOME2 Accesibility themes :

[Icon Theme]

Name=HighContrastLargePrint

Comment=High Contrast Large Icon Theme

Directories=48x48/filesystems,scalable/mimetypes

Inherits=gnome

[48x48/filesystems]

Size=48

Context=FileSystems

Type=Threshold

[scalable/mimetypes]

MinSize=1

Size=128

MaxSize=256

Context=MimeTypes

Type=Scalable


need to add a link to the whole frelling thing.... should we create another html, or just link to bonsai or the like?

The Full file can be seen here.

Step 2. General Directory and Icon Layout

Once you have a basic index.theme, the next step is to make the actual icon directories, and place the right icons in the right directories. First off, it should made apperant that the Directory entries you put in Index.theme are the actual names of the directories, so if you have a [48x48/filesystems] section in the index.theme, you should have a corresponding folder 48x48/filesystems, and so forth. So, for the above example your should have a directory layout something like this:


HighContrastLargePrint/

48x48/

actions/

apps/

devices/

mimetypes/

scalable/

actions/

apps/

devices/

mimetypes/

index.theme

As you can see the actual directory layout is the same layout as is described in the index.theme, making both updating the directory to match the index, or the index to match the layout very very easy.

Once you have created the directories you need, you need to organize the icons first by size and then by context, again exactly as is layed out in the index. So any 48x48 icons will go somewhere into the 48x48/ subdirectory tree by context.

Step 3. Icon naming & organization

In general icons are simply and intuitively named, and in fact the general name format is quite similar to that of the original Nautilus icon names - each icon has a root name representing the specific use it is intended for, 'directory' for directories, 'ftp' for ftp folders, 'blockdev' for block devices etc, and a prefix representing the desktop it is intended for [1], such as 'gnome-' for GNOME. Depending on the icon and the context within which it is used, the actual icon name may also have a prefix representing that context, and possibly multiple other prefixes representing more specific sub-contexts. For each root name, there may also be multiple icons, where each will also include a suffix representing the additional states a particular icon is intended for.

To summarize, in general an icon will be of the format :

desktop-[context-][subcontext1-,...] specific use [-icon state]

A simple example of this format would be 'gnome-fs-directory', where 'gnome-' represents the target desktop, 'fs-'represents the general context, FileSystem; and 'directory' is the specific use, aka directories. Another example of an icon name is 'gnome-mime-application-pdf', where again 'gnome-' represents the target desktop, 'mime-' represents the general context MimeTypes, 'application-' represents a subcontext, aka what "kind" of MimeType; and 'pdf' represents the specific use, in this case pdf documents.

the specific breakdown of the icons by context is as follows :


Filesystem

The FileSystem context is for icons intended to be used by a FileManager, such as Nautilus, to represent the core parts of a directory tree, essentially such icons as would be used to represent Folders, Network Servers, Network workstations, Fifo's, Character Devices, Executables and so forth.

For this context, every theme should probably have an icon representing

Block Devices -
list common block devices, and have an example block device icon, perhaps from the gnome or HighContrast themes."

gnome-fs-blockdev

Bookmarks -
list common uses for bookmarks, and have an example of both icons"

gnome-fs-bookmark


if a boomark is missing/removed etc the missing icon will be displayed instead.

gnome-fs-bookmark-missing

Character Devices-

list common character devices, and have an example character device icon, perhaps from the gnome or HighContrast themes."

gnome-fs-chardev

Directories-

gnome-fs-directory


the accept icon is for when dragging items over/into the folder etc..

gnome-fs-directory-accept

Executables -

gnome-fs-executable

fifos -

gnome-fs-fifo

ftp directories -

gnome-fs-ftp

home directories -

gnome-fs-home

network neighborhood -

gnome-fs-network

network workstations -

network shares -

gnome-fs-share

network servers -

gnome-fs-server

mounted nfs shares -

gnome-fs-nfs

mounted smb shares -

gnome-fs-smb

sockets -

gnome-fs-socket

the trash can -

gnome-fs-trash-empty

gnome-fs-trash-full



gnome-fs-loading-icon

gnome-fs-regular

gnome-fs-ssh

gnome-fs-web

Put more descriptive breakdown here about the icon names, describing what each icon is used for. It shouldn't need much as the names are farely self-explanatory...

Devices

The Device context is for icons intended to be used to represent commonly used devices, such as CDROM, DVD, Floppy etc, from within a Desktop Manager, and/or a FileManager to diplay mounted hardware devices. These icons will usually have a context prefix of 'dev-'(i.e. cdrom = gnome-dev-cdrom).

For this context, every theme should probably have an icon representing

cdrom-audio -

cdrom -

dvd -

floppy -

harddisk -

jazdisk -

memory -

zipdisk -


gnome-dev-cdrom-audio

gnome-dev-cdrom

gnome-dev-dvd

gnome-dev-floppy

gnome-dev-harddisk

gnome-dev-jazdisk

gnome-dev-memory

gnome-dev-zipdisk

Put more descriptive breakdown here about the icon names, describing what each icon is used for. It shouldn't need much as the names are farely self-explanatory...

MimeTypes

Icons for MimeTypes such as msword, html or pdf will go into the mimetypes folder, the folder in the index matching the Size=48, and Context=MimeTypes. In the case of this example the mimetypes folder is "mimetypes".

Clean this sentance up, the whole gnome- vs gnome-mime- is a bit confusing..

Icons in this folder are all named essentially like the FileSystem icons, except that mimetypes use mime- instead of fs-, except on system types such as package or library, where niether is needed, in other words each icon is expected to be prefixed with gnome-, and mimetypes with gnome-mime-. More specifically here are a handefull of the 120 standard icons such as are set by the default Gnome icon theme :

gnome-compressed

gnome-library

gnome-mime-application-msword

gnome-mime-application-pdf

gnome-mime-application-pgp-encrypted

gnome-mime-application-pgp-keys

gnome-mime-application-pgp

gnome-mime-application-postscript

gnome-mime-application-qif

gnome-mime-application-rtf

gnome-package

Put more descriptive breakdown here about the icon names, describing what each icon is used for. It shouldn't need much as the names are farely self-explanatory...

Applications

Application icons, usually for GNOME specific applications such as gnome-starthere, will go into the applications folder, the folder in the index matching the Size=48, and Context=Applications. In the case of this example the applications folder is "apps".

Icons in this folder are all named essentially like the FileSystem icons, except that the fs- is not needed, so each icon is expected to be prefixed with gnome-. More specifically here are those standard icons such as are set by the default Gnome icon theme :

gnome-desktop-config

gnome-server-config

gnome-starthere

gnome-system-config

Put more descriptive breakdown here about the icon names, describing what each icon is used for. It shouldn't need much as the names are farely self-explanatory...

Emblems

Emblems


Put more descriptions about the icon names expected here, including a list of the most common emblems.

What about ACTIONS, what is the proper layout?
Notes
[1] 	

this is for future compatibility with multiple other desktops, where for instance the theme could provide icons for KDE, prefixed with something else such as 'kde-', in the same directory as GNOME icons.
